Spring AI 2.0 实战：用Java快速搭建RAG知识库系统

// 依赖：spring-ai-vector-store-advisor（2.0 中由 spring-ai-advisors-vector-store 更名而来）
// 场景：知识库问答的最小可行版本

var qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder()
                .similarityThreshold(0.55) // 示意值：请先按 7.1 节打印真实分数，再确定自己的阈值
                .topK(5)                  // 只取最相关的5个片段
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(qaAdvisor)
        .user("公司报销流程是怎样的？")
        .call()
        .content();

// 依赖：spring-ai-rag
// 场景：需要精细控制检索阈值、返回数量的标准RAG流程

var ragAdvisor = RetrievalAugmentationAdvisor.builder()
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .vectorStore(vectorStore)
                .similarityThreshold(0.55) // 示意值：请先按 7.1 节打印真实分数，再确定自己的阈值
                .topK(6)
                .build())
        .build();

String answer = chatClient.prompt()
        .advisors(ragAdvisor)
        .user("最新版的产品保修政策有哪些变化？")
        .call()
        .content();

// 场景：用户问题较模糊，先改写，再扩展成多个子查询
// 官方建议：给 QueryTransformer 使用的 ChatClient 配置低温度（如 0.0），结果更稳定
// 2.0 中 Options 通过构建器创建，defaultOptions 接收 ChatOptions.Builder

ChatClient.Builder lowTempBuilder = chatClientBuilder.clone()
        .defaultOptions(ChatOptions.builder().temperature(0.0));

var advancedRagAdvisor = RetrievalAugmentationAdvisor.builder()
        // 第一步：改写查询
        .queryTransformers(RewriteQueryTransformer.builder()
                .chatClientBuilder(lowTempBuilder)
                .build())
        // 第二步：扩展为3个角度的子查询（默认包含原始查询）
        .queryExpander(MultiQueryExpander.builder()
                .chatClientBuilder(lowTempBuilder)
                .numberOfQueries(3)
                .build())
        // 第三步：对每个子查询做向量检索
        .documentRetriever(VectorStoreDocumentRetriever.builder()
                .vectorStore(vectorStore)
                .similarityThreshold(0.5)
                .topK(8)
                .build())
        .build();

// 场景：用Tika统一解析PDF/Word等多种格式文档
// 依赖：spring-ai-tika-document-reader

@Component
public class KnowledgeBaseReader {

    public List<Document> loadDocuments(Resource resource) {
        // TikaDocumentReader 底层基于 Apache Tika，支持PDF/DOC/DOCX/PPT/PPTX/HTML等格式
        TikaDocumentReader reader = new TikaDocumentReader(resource);
        return reader.read();
    }
}

// 场景：把长文档按Token数量切分成适合Embedding模型处理的小块
// chunkSize过大会稀释语义，过小会丢失上下文，需要结合业务文档长度调优

@Bean
public TextSplitter textSplitter() {
    return TokenTextSplitter.builder()
            .withChunkSize(800)          // 目标块大小（Token），默认800
            .withMinChunkSizeChars(350)  // 每块最少字符数，默认350
            // 中英文标点一起配置，让分块尽量在句子边界截断
            .withPunctuationMarks(List.of('。', '？', '！', '；', '.', '?', '!', '\n'))
            .build();
}

// 组装完整的ETL入库流程
@Component
public class EtlPipeline {

    private final VectorStore vectorStore;
    private final TextSplitter textSplitter;
    private final KnowledgeBaseReader documentReader;

    public EtlPipeline(VectorStore vectorStore, TextSplitter textSplitter,
                       KnowledgeBaseReader documentReader) {
        this.vectorStore = vectorStore;
        this.textSplitter = textSplitter;
        this.documentReader = documentReader;
    }

    public void ingest(Resource resource, String docId) {
        // 先删除该文档的旧分块，避免重复上传后答案重复
        vectorStore.delete(new FilterExpressionBuilder().eq("docId", docId).build());

        List<Document> rawDocuments = documentReader.loadDocuments(resource);
        // 给每个原始文档打上标识，分块时元数据会复制到所有子块
        rawDocuments.forEach(d -> d.mutate().metadata("docId", docId).build());

        List<Document> chunks = textSplitter.apply(rawDocuments);
        vectorStore.write(chunks);
    }
}

// 场景：暴露"上传文档"和"知识库问答"两个REST接口
// 说明：省略 import，使用 IDE 自动导入即可

@RestController
@RequestMapping("/api/knowledge-base")
public class KnowledgeBaseController {

    // 请求体使用 record，前端传 {"question": "..."}
    public record AskRequest(String question) {}

    private final ChatClient chatClient;
    private final EtlPipeline etlPipeline;

    public KnowledgeBaseController(ChatClient.Builder chatClientBuilder,
                                   VectorStore vectorStore,
                                   EtlPipeline etlPipeline,
                                   @Value("${rag.similarity-threshold:0.3}") double threshold,
                                   @Value("${rag.top-k:6}") int topK) {
        this.etlPipeline = etlPipeline;

        // 第一步：组装 RAG Advisor
        var ragAdvisor = RetrievalAugmentationAdvisor.builder()
                .documentRetriever(VectorStoreDocumentRetriever.builder()
                        .vectorStore(vectorStore)
                        .similarityThreshold(threshold)
                        .topK(topK)
                        .build())
                .build();

        // 第二步：注册为 ChatClient 的默认 Advisor
        this.chatClient = chatClientBuilder
                .defaultSystem("你是企业知识库助手，只依据检索到的资料回答问题，并使用中文作答。"
        + "如果资料中没有明确答案，请直接回答\"根据现有资料无法回答\"，不要推测或补充资料之外的内容。")
                .defaultAdvisors(ragAdvisor)
                .build();
    }

    // 上传文档并入库
    @PostMapping("/documents")
    public String upload(@RequestParam("file") MultipartFile file) {
        etlPipeline.ingest(file.getResource(), file.getOriginalFilename());
        return "ok";
    }

    // 知识库问答
    @PostMapping("/ask")
    public String ask(@RequestBody AskRequest request) {
        return chatClient.prompt()
                .user(request.question())
                .call()
                .content();
    }
}

// 场景：用阈值0（接受全部）+ 较大topK，观察真实的相似度分布，再决定阈值
var probe = VectorStoreDocumentRetriever.builder()
        .vectorStore(vectorStore)
        .similarityThreshold(0.0)
        .topK(10)
        .build();

probe.retrieve(new Query("公司报销流程是怎样的？"))
        .forEach(doc -> System.out.printf("%.3f | %s%n", doc.getScore(), doc.getText()));

// ❌ 错误示范：阈值设得过低，大量不相关片段被塞进上下文，稀释真正有用的信息
VectorStoreDocumentRetriever.builder()
        .vectorStore(vectorStore)
        .similarityThreshold(0.1)
        .topK(20)
        .build();

// ✅ 示范（0.55 与 6 均为示意值，以你的实测分布为准）
VectorStoreDocumentRetriever.builder()
        .vectorStore(vectorStore)
        .similarityThreshold(0.55)
        .topK(6)
        .build();